home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / co256-05 / col256.doc < prev    next >
Encoding:
Text File  |  1993-12-31  |  14.3 KB  |  372 lines
  1.  
  2. COL256 description.
  3. ===================
  4.  
  5.  
  6.  
  7. What is COL256?
  8. ===============
  9.  
  10.   COL256 is a unit developed for Borland Pascal 7.0 to have access to video
  11.   modes with 256 colors and a 'high' resolution (more than 320x200).
  12.   I decided to program it as a unit to be independent of Borlands GRAPH unit
  13.   and to get my own expieriences in graphics programming on a IBM-PC.
  14.  
  15.  
  16. IMPORTANT
  17. =========
  18.  
  19.   It is just a prerelease to have it tested on several machines. Eventhough I
  20.   designed it carefully using standard VGA frequencies I could not guarantee
  21.   that it works properly on YOUR machine, YOUR card and YOUR monitor.
  22.  
  23.          ----\\   ESPECIALLY I WOULD TAKE *NO* RESPONSIBILITY   //----
  24.   ---======== >>  FOR ANY DAMAGE TO YOUR HARDWARE OR ANYTHING  << ========---
  25.          ----//   ELSE CAUSED BY USING THIS PACKAGE.            \\----
  26.  
  27.   If you have tested it on your machine and it worked well please send me a
  28.   short note containing information about your graphics card and monitor
  29.   (manufacturer, type,...). You might use the SPEED program and send me the 
  30.   LOGFILE created by SPEED. !! PLEASE ONLY EMail !!
  31.  
  32.  
  33. Features of COL256
  34. ==================
  35.  
  36.   COL256 supports:
  37.  
  38.       * graphic modes with a resolution of 320 or 360 pixels horizontally
  39.         and 200,240,400 or 480 pixels vertically in ANY combination on
  40.         almost EVERY (register compatible) VGA.
  41.  
  42. ==>     ^^^^^^ 'almost' because I would not guarantee that it runs on
  43. ==>            YOUR VGA, but I checked it on a lot of cards and it worked
  44. ==>            well.
  45.  
  46.       * virtual screen programming
  47.  
  48.       * Support of soft scrolling/panning of the vitrual screen
  49.  
  50.       * fast assembly routines to achieve high graphics performance and
  51.         compact code
  52.  
  53.       * several pages supported if enough memory would be availiable on a
  54.         256 Kbyte VGA (even for virtual screens).
  55.  
  56.       * both DOS real mode and DOS protected mode
  57.  
  58.       * palette manipulation without using BIOS (thus avoiding flicker on
  59.         screen, many BIOS'es don't care about this) so that you would be
  60.         able to implement fine palette animations.
  61.  
  62.       * hardware bit manipulations as supported by a standard VGA
  63.  
  64.       * free definable clipping window
  65.  
  66.       * error reporting similar to Borlands GRAPH unit.
  67.         (Some errors will not occur, because features are not implemented
  68.          yet.)
  69.  
  70.  
  71.   Future Plans:
  72.  
  73.       * Support of Borland's stroke fonts (.CHR), standard BIOS bitmap fonts
  74.         and free defined 'sprite' fonts.
  75.  
  76.       * extended drawing routines (circles, ellipses, filling, etc)
  77.  
  78.       * full support of bitmap routines
  79.  
  80.       * support of higher resolutions of virtual screens using more than 256k
  81.         video memory
  82.  
  83.       * GetErrorText function to make error reporting easier
  84.  
  85.       * TP 6.0 support
  86.  
  87.       * better debugging support
  88.  
  89.  
  90. System requirements
  91. ===================
  92.  
  93.   COL256 runs only on 286 or higher, so be sure to check if a 286 (or higher)
  94.   processor is present (eventhough I think a 8086 with a VGA running at high
  95.   resolution graphic modes would be a strange hardware combination).
  96.   During mode initialisation COL256 will check if a VGA is present, but I'm
  97.   NOT checking if it is register compatible.
  98.  
  99.  
  100. How to use it
  101. =============
  102.  
  103.   As usual you would have to include COL256 in your 'uses' list at the
  104.   beginning of your program and include the directory where the TPU/TPP files
  105.   located in your unit path. Then use the graphic procedures as described
  106.   below.
  107.  
  108.  
  109. COL256 types and variables
  110. ==========================
  111.  
  112.   The used types for palette maipulation routines are declared as follows:
  113.  
  114.       type   TColor    = record r,g,b:byte end;
  115.              TPalette  = array[0..256] of TColor;
  116.  
  117.   Thus TColor holds a RGB tripel, where r,g and b values are from 0..63
  118.   and TPalette holds 256 of those RGB tripel, describing the full palette.
  119.  
  120.   Constants declared by COL256 are
  121.  
  122.     * Mode-ID's for suported video modes:
  123.  
  124.        M320x200 = 0;    M320x240 = 1;    M320x400 = 2;   M320x480 = 3;
  125.        M360x200 = 4;    M360x240 = 5;    M360x400 = 6;    M360x480 = 7;
  126.  
  127.        NotMemClear = $8000;  NoStateInit = $4000;
  128.  
  129.       If bit 15 of <mode> is set, video memory will not be initialized
  130.       (filled with 00h) during mode initialization.  If bit 14 of <mode> is
  131.       set, no state initialisation (grCursor,...) will be performed.
  132.       (See EnterGraphMode for detail.)
  133.  
  134.       Note: y-resolution is given by bits 0 and 1,
  135.             x-resolution is given by bit 2
  136.  
  137.     * Values for error reporting (same as from GRAPH):
  138.  
  139.        grOk        =   0;    { No error                 }
  140.        grNoInitGraph    =  -1;    { BGI graphics not installed          }
  141.        grNotDetected    =  -2;    { Graphics hardware not found          }
  142.        grFileNotFound    =  -3;    { Device driver file (.BGI) not found   }
  143.        grInvalidDriver    =  -4;    { Invalid device driver file         }
  144.        grNoLoadMem    =  -5;    { Not enough memory to load driver    }
  145.        grNoScanMem    =  -6;    { Out of memory in scanfill        }
  146.        grNoFloodMem    =  -7;    { Out of memory in flood fill        }
  147.        grFontNotFound    =  -8;    { Fontfile (.CHR) not found        }
  148.        grNoFontMem    =  -9;    { Not enough memory to load font    }
  149.        grInvalidMode    = -10;    { Invalid graphics mode (not supported) }
  150.        grError        = -11;    { Graphics error (generic error)    }
  151.        grIOerror    = -12;    { graphics I/O error (file access)    }
  152.        grInvalidFont    = -13;    { Invalid font file            }
  153.        grInvalidFontNum = -14;    { Invalid font number            }
  154.  
  155.     * Write mode constants for SetWriteMode
  156.  
  157.        NormalPut       =  0;   { 00000_b }
  158.        AndPut          =  8;   { 01000_b }
  159.        OrPut           = 16;   { 10000_b }
  160.        XorPut          = 24;   { 11000_b }
  161.  
  162.       Note: Use this constants, first your code gets better readable and
  163.             second they are NOT the same as GRAPH's BitBlt constants.
  164.  
  165.     * Initialized Variables:
  166.  
  167.        const ActiveMode : integer = -1;
  168.          OldMode    : integer = -1;
  169.  
  170.       ActiveMode holds the mode-ID of the current mode. OldMode holds the
  171.       video mode (as BIOS told me) before the first EnterGraphMode call.
  172.  
  173.     * Variables:
  174.        var    xMin,xMax,
  175.           yMin,yMax,
  176.               ActivePage,VisualPage,
  177.           grCurX,grCurY    : integer;
  178.  
  179.           GetX        : integer absolute grCurX;
  180.           GetY        : integer absolute grCurY;
  181.           GetMaxX        : integer absolute xMax;
  182.           GetMaxY        : integer absolute yMax;
  183.           GetMinX        : integer absolute xMax;
  184.           GetMinY        : integer absolute yMax;
  185.               GetVisualPage     : integer absolute VisualPage;
  186.               GetActivePage     : integer absolute ActivePage;
  187.  
  188.       As you can see I mapped variables with the same names as the
  189.       corresponding GRAPH functions at my internal stuff. This should be
  190.       faster than function calls to get actual graphics position etc.
  191.       But because I use them also for internal purposes do NEVER write
  192.       to these variables; use the provided functions/procedures to modify
  193.       them !
  194.  
  195.  
  196. COL256 procedures and variables
  197. ===============================
  198.  
  199.     procedure EnterGraphMode  (Mode:word);
  200.  
  201.       Initializes the mode given by the Mode value by resetting the hardware,
  202.       initializing internal tables/variables and clearing video memory if
  203.       required. (See constants for modes supported.)
  204.       If NoStateInit is set, the selected clipwindow, the selected pages and
  205.       the graphics cursor would not be initialized (with all consequences).
  206.  
  207.  
  208.     procedure ExitGraphMode;
  209.  
  210.       Initializes the old mode set before the first EnterGraphMode call 
  211.       using BIOS.
  212.  
  213.  
  214.     function  GetModeName(mode:integer):string;
  215.  
  216.       Returns a string describing the mode given by the mode ID, such as
  217.       '320x240, 256 colors' for mode=M320x240 and 'Invalid Mode' for mode=12.
  218.  
  219.  
  220.     procedure SetVirtualScreen(xRes,yRes:integer);
  221.  
  222.       Set up a virtual screen with higher 'resolution' than the one given
  223.       by the initialized CRT mode.
  224.  
  225.  
  226.     procedure SetVisualScreen (x,y:integer);
  227.  
  228.       Determine the visible part of the vitual screen:
  229.  
  230.        +----------------------- xRes ------------------------------------+
  231.        |           |                                                     |
  232.        |           y                                                     |
  233.        |           |                                                     |
  234.        |---- x ----+--------- xVis -------------+                        |
  235.        |           |                            |                        |
  236.        |           |
  237.        |                                        e                        e
  238.                    y                            g                        g
  239.        y           V                            .                        .
  240.        R           i                            2                        5
  241.        e           s                            0                        0
  242.        s                                        0                        0
  243.                    |
  244.        |           |visible screen              |                        |
  245.        |           +-------- eg.320 ------------+                        |
  246.        |                                                                 |
  247.        |                                                                 |
  248.        |virtual screen                                                   |
  249.        +------------------------- eg.500 --------------------------------+
  250.  
  251.  
  252.     procedure SetClipWindow   (x1,y1,x2,y2:integer);
  253.  
  254.       Sets the clipwindow to a rectangle defined by x=x1,x=x2,y=y1,y=y2 so that
  255.       drawing operations would only be done inside the clipwindow. This does
  256.       not modify the xMax,yMax,xMin,yMin variables, they are holding the
  257.       resolution of the (virtual) screen.
  258.  
  259.  
  260.     procedure unSetClipWindow;
  261.  
  262.       As the name implies, the clipwindow would be set to the whole (virtual)
  263.       screen.
  264.  
  265.  
  266.     procedure SetActivePage   (PageNo:integer);
  267.     procedure SetVisualPage   (PageNo:integer);
  268.     procedure SwitchPages;
  269.  
  270.       These procedures should be used to change pages. Read/write operations
  271.       are ever done to the ActivePage and the VisualPage is shown on the
  272.       output device (monitor or something you have conected to your VGA,
  273.       whatever it is).
  274.  
  275.  
  276.     procedure setWriteMode    (Mode,Rotation:byte);
  277.  
  278.       The VGA supports bit manipulation of the data written to the video
  279.       memory and the contents of the memory. This is done in the following
  280.       way:
  281.            - contents of the video memory is loaded into an internal buffer
  282.            - the data to be written is rotated right by the specified
  283.              number of bits
  284.            - the specified operation (OR,AND,XOR,Nothing) is applied to the
  285.              contents of the buffer and the rotated data
  286.            - the result is written back to video memory
  287.  
  288.       All drawing routines (with one exception) work independent of the
  289.       WriteMode set. The exception are routines ending with a '_', they will
  290.       work correctly only if the WriteMode is NormalPut and no rotation is
  291.       selected, but they are twice as fast as the other routines.
  292.  
  293.  
  294.     function  GraphResult:integer;
  295.  
  296.       Returns the result of the last graphics operation and cleares the
  297.       internal error variable.
  298.  
  299.  
  300.     procedure moveto          (x,y:integer);
  301.     procedure moverel         (x,y:integer);
  302.  
  303.       Moves the graphics cursor to the specified position. (Either to
  304.       an absolute position or relative to the actual value.
  305.       Note: The graphics cursor would never be clipped!
  306.  
  307.  
  308.     procedure scnclr          (col:byte);
  309.  
  310.       Clear the screen by filling the ActivePage with color col.
  311.  
  312.  
  313.     procedure pset            (x,y:integer; c:byte);        { set point }
  314.     function  ptest           (x,y:integer):byte;          { test point }
  315.     procedure LineH           (xa,xe,y:integer; c:byte);  { horiz. line }
  316.     procedure LineV           (x,ya,ye:integer; c:byte);   { vert. line }
  317.     procedure Line            (x1,y1,x2,y2:integer; c:byte);     { line }
  318.     procedure LineRel         (x,y:integer; c:byte);{line, rel to Cursor}
  319.     procedure LineTo          (x,y:integer; c:byte);
  320.  
  321.     procedure LineH_          (xa,xe,y:integer; c:byte);
  322.     procedure LineV_          (x,ya,ye:integer; c:byte);
  323.     procedure Line_          (x1,y1,x2,y2:integer; c:byte);
  324.     procedure LineRel_        (x,y:integer; c:byte);
  325.     procedure LineTo_         (x,y:integer; c:byte);
  326.  
  327.     procedure Box(x1,y1,x2,y2:integer;color:byte);   { filled rectangle }
  328.     procedure Rectangle(x1,y1,x2,y2:integer;color:byte);
  329.  
  330.       I think, the names explain what these procedures are doing.
  331.  
  332.  
  333.     procedure PutImage          (x,y:integer; var Image); { put bitmap data }
  334.     procedure PutImageNonZero (x,y:integer; var Image);
  335.     procedure PutImage_       (x,y:integer; var Image);
  336.     procedure PutImageNonZero_(x,y:integer; var Image);
  337.  
  338.       This gives you the opportunity to put bitmap data on the screen, the
  339.       format of buffer is as follows:
  340.  
  341.           Buffer = record xSize,ySize : word;
  342.                           data: array[ySize,xSize] of byte;
  343.                    end;
  344.  
  345.       The PutImageNonZero puts only bytes <> zero, so that you would have a
  346.       easy way to do masking and drawing just at one time.
  347.  
  348.     procedure SetColor(nr:byte; col:TColor);
  349.     procedure SetPal(var pal:TPalette);
  350.     procedure GetPal(var pal:TPalette);
  351.  
  352.       Use these procedures to modify the palette and color values. It should
  353.       be clear what they do.
  354.  
  355.  
  356. Credits
  357. =======
  358.  
  359.     COL256 has been developed by Steffen Seeger using BORLAND's great BP 7.0
  360.     package. It (COL256) is free for PRIVATE use, if you want to use it in 
  361.     your company or institution or your commercial programs contact me 
  362.     (It wouldn't be fair if you do not, because I'm a student and I spent a 
  363.     lot of spare time developing this package).
  364.  
  365.     (C) 1993 Steffen Seeger, all rights reserved. 
  366.  
  367. ===============================================================================
  368. |   Steffen Seeger                  | InterNet: Seeger.Physik.TU-Chemnitz.DE  |
  369. |   Carl-von-Ossietzky-Str. 193     |                          |
  370. |   Chemnitz (Germany)              |                          |
  371. |   09127                           |                          |
  372. ===============================================================================